---
type: integration
title: '@astrojs/cloudflare'
description: "Apprendre à utiliser l'adaptateur SSR @astrojs/cloudflare pour déployer votre projet Astro."
githubIntegrationURL: 'https://github.com/withastro/adapters/tree/main/packages/cloudflare/'
category: adapter
i18nReady: true
---

import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'

Cet adaptateur permet à Astro de déployer votre [site rendu `hybrid` ou `server`](/fr/basics/rendering-modes/#rendu-à-la-demande) sur [Cloudflare](https://www.cloudflare.com/).

Si vous utilisez Astro comme [constructeur de sites statiques](/fr/basics/rendering-modes/#pré-rendu), vous n'avez pas besoin d'adaptateur.

Découvrez comment déployer votre site Astro dans notre [Guide de déploiement des pages Cloudflare](/fr/guides/deploy/cloudflare/).

## Pourquoi Astro Cloudflare

[Cloudflare](https://www.cloudflare.com/) fournit des CDN, de la sécurité web et d'autres services. Cet adaptateur améliore le processus de construction d'Astro pour préparer votre projet à être déployé via Cloudflare.

## Installation

Astro inclut une commande `astro add` pour automatiser l'installation des intégrations officielles. Si vous préférez, vous pouvez [installer les intégrations manuellement](#installation-manuelle) à la place.

Ajoutez l'adaptateur Cloudflare pour activer SSR dans votre projet Astro avec la commande `astro add`. Cela installera `@astrojs/cloudflare` et apportera les changements appropriés à votre fichier `astro.config.mjs` en une seule étape.

<PackageManagerTabs>
  <Fragment slot="npm">
    ```sh
    npx astro add cloudflare
    ```
  </Fragment>
  <Fragment slot="pnpm">
    ```sh
    pnpm astro add cloudflare
    ```
  </Fragment>
  <Fragment slot="yarn">
    ```sh
    yarn astro add cloudflare
    ```
  </Fragment>
</PackageManagerTabs>

### Installation manuelle

Tout d'abord, ajoutez l'adaptateur `@astrojs/cloudflare` aux dépendances de votre projet en utilisant votre gestionnaire de paquets préféré.

<PackageManagerTabs>
  <Fragment slot="npm">
    ```sh
    npm install @astrojs/cloudflare
    ```
  </Fragment>
  <Fragment slot="pnpm">
    ```sh
    pnpm add @astrojs/cloudflare
    ```
  </Fragment>
  <Fragment slot="yarn">
    ```sh
    yarn add @astrojs/cloudflare
    ```
  </Fragment>
</PackageManagerTabs>

Ensuite, ajoutez l'adaptateur et votre [mode de rendu à la demande](/fr/basics/rendering-modes/#rendu-à-la-demande) à votre fichier `astro.config.mjs` :

```js title="astro.config.mjs" ins={2,5-6}
import { defineConfig } from 'astro/config';
import cloudflare from '@astrojs/cloudflare';

export default defineConfig({
  output: 'server',
  adapter: cloudflare(),
});
```

## Options

### mode

<p>

  **Type :** `'advanced' | 'directory'`<br />
  **Par défaut :** `'advanced'`
</p>

Cette option de configuration définit la manière dont votre projet Astro est déployé sur les pages Cloudflare.

* Le mode `advanced` récupère le fichier `_worker.js` dans le dossier `dist`.
* Le mode `directory` récupère les fichiers dans le dossier `functions`, par défaut un seul fichier `[[path]].js` est généré.

Le passage en mode répertoire vous permet d'ajouter manuellement des fichiers supplémentaires tels que [Cloudflare Pages Plugins](https://developers.cloudflare.com/pages/platform/functions/plugins/), [Cloudflare Pages Middleware](https://developers.cloudflare.com/pages/platform/functions/middleware/) ou des fonctions personnalisées à l'aide de [Cloudflare Pages Functions Routing](https://developers.cloudflare.com/pages/platform/functions/routing/).

```js title="astro.config.mjs" ins="mode: 'directory'"
export default defineConfig({
  adapter: cloudflare({ mode: 'directory' }),
});
```

Pour compiler un bundle séparé pour chaque page, définissez l'option `functionPerRoute` dans la configuration de votre adaptateur Cloudflare. Cette option nécessite une maintenance manuelle du dossier `functions`. Les fichiers émis par Astro écraseront les fichiers existants avec des noms identiques dans le dossier `functions`, vous devez donc choisir des noms de fichiers uniques pour chaque fichier que vous ajoutez manuellement. De plus, l'adaptateur ne videra jamais le dossier `functions` des fichiers obsolètes, vous devez donc nettoyer le dossier manuellement lorsque vous supprimez des pages.

```js title="astro.config.mjs" ins={7}
import {defineConfig} from "astro/config";
import cloudflare from '@astrojs/cloudflare';

export default defineConfig({
  adapter: cloudflare({
    mode: 'directory',
    functionPerRoute: true
  })
})
```

Cet adaptateur ne supporte pas l'option [`edgeMiddleware`](/fr/reference/adapter-reference/#edgemiddleware).

### routes.strategy

<p>

  **Type :** `'auto' | 'include' | 'exclude'`<br />
  **Par défaut :** `'auto'`
</p>

Détermine comment `routes.json` sera généré si aucun [`_routes.json`](#_routesjson-personnalisé) personnalisé n'est fourni.

Il y a trois options disponibles :

* **`"auto"` (par défaut) :** Sélectionne automatiquement la stratégie qui génère le moins d'entrées. Cela devrait presque toujours être suffisant, donc choisissez cette option à moins que vous n'ayez une raison spécifique de ne pas le faire.

* **`include` :** Les pages et les points de terminaison (endpoints) qui ne sont pas pré-rendus sont listés en tant qu'entrées `include` indiquant à Cloudflare d'invoquer ces routes en tant que fonctions. Les entrées `exclude` ne sont utilisées que pour résoudre les conflits. C'est généralement la meilleure stratégie lorsque votre site web a principalement des pages statiques et seulement quelques pages dynamiques ou points de terminaison.

    Exemple : Pour `src/pages/index.astro` (statique), `src/pages/company.astro` (statique), `src/pages/users/faq.astro` (statique) et `/src/pages/users/[id].astro` (SSR) cela produira les `_routes.json` suivantes :

    ```json
    {
      "version": 1,
      "include": [
        "/_image", // Point de terminaison pour les images
        "/users/*" // Route dynamique
      ],
      "exclude": [
        // Routes statiques qui doivent être exemptées de la route dynamique à caractères génériques ci-dessus
        "/users/faq/",
        "/users/faq/index.html"
      ]
    }
    ```

* **`exclude` :** Les pages pré-rendues sont listées en tant qu'entrées `exclude` (indiquant à Cloudflare de traiter ces routes comme des actifs statiques). C'est généralement la meilleure stratégie lorsque votre site web a principalement des pages dynamiques ou des points de terminaison et seulement quelques pages statiques.

    Exemple : Pour les mêmes pages que dans l'exemple précédent, cela produira le `_routes.json` suivant :

    ```json
    {
      "version": 1,
      "include": [
        "/*" // Tout se déroule comme prévu, à l'exception des routes ci-dessous
      ],
      "exclude": [
        // Tous les contenus actifs
        "/",
        "/company/",
        "/index.html",
        "/users/faq/",
        "/favicon.png",
        "/company/index.html",
        "/users/faq/index.html"
      ]
    }
    ```

### routes.include

<p>

  **Type :** `string[]`<br />
  **Par défaut :** `[]`
</p>

Si vous voulez utiliser la génération automatique de `_routes.json`, mais que vous voulez inclure des routes supplémentaires (par exemple, lorsque vous avez des fonctions personnalisées dans le dossier `functions`), vous pouvez utiliser l'option `routes.include` pour ajouter des routes supplémentaires au tableau `include`.

### routes.exclude

<p>

  **Type :** `string[]`<br />
  **Par défaut :** `[]`
</p>

Si vous voulez utiliser la génération automatique de `_routes.json`, mais que vous voulez exclure des routes supplémentaires, vous pouvez utiliser l'option `routes.exclude` pour ajouter des routes supplémentaires au tableau `exclude`.

L'exemple suivant génère automatiquement `_routes.json` en incluant et en excluant des routes supplémentaires. Notez que cela n'est nécessaire que si vous avez des fonctions personnalisées dans le dossier `functions` qui ne sont pas gérées par Astro.

```js title="astro.config.mjs" ins={4-8}
export default defineConfig({
  adapter: cloudflare({
    mode: 'directory',
    routes: {
      strategy: 'include',
      include: ['/users/*'], // géré par une fonction personnalisée : functions/users/[id].js
      exclude: ['/users/faq'], // géré par une page statique : pages/users/faq.astro
    },
  }),
});
```

### imageService

<p>

  **Type :** `'passthrough' | 'cloudflare' | 'compile'`<br />
  **Par défaut :** `'passthrough'`
</p>

Détermine quel service d'image est utilisé par l'adaptateur. L'adaptateur utilisera par défaut le mode `passthrough` si un service d'image incompatible est configuré. Sinon, il utilisera le service d'image configuré globalement :

* **`cloudflare`:** Utilise le service [Cloudflare Image Resizing](https://developers.cloudflare.com/images/image-resizing/).
* **`passthrough`:** Utilise le service existant [`noop`](/fr/guides/images/#configurer-le-service-no-op-passthrough).
* **`compile`:** Utilise le service par défaut d'Astro (sharp), mais seulement sur les routes pré-rendues au moment de la compilation. Pendant le SSR pour les pages rendues à la demande, toutes les fonctionnalités de `astro:assets` sont désactivées.

```js title="astro.config.mjs" ins={6}
import {defineConfig} from "astro/config";
import cloudflare from '@astrojs/cloudflare';

export default defineConfig({
  adapter: cloudflare({
     imageService: 'cloudflare'
  }),
  output: 'server'
})
```

### `wasmModuleImports`

<p>

  **Type :** `true | false`<br />
  **Par défaut :** `false`
</p>

Importer ou non les fichiers `.wasm` directement en tant que [modules ES](https://github.com/WebAssembly/esm-integration/tree/main/proposals/esm-integration).

Ajouter `wasmModuleImports: true` à `astro.config.mjs` pour l'activer à la fois dans la version Cloudflare et dans le serveur de développement Astro. En savoir plus sur l'[utilisation des modules Wasm](#utilisation-des-modules-wasm).

```js title="astro.config.mjs" ins={6}
import {defineConfig} from "astro/config";
import cloudflare from '@astrojs/cloudflare';

export default defineConfig({
  adapter: cloudflare({
     wasmModuleImports: true
  }),
  output: 'server'
})
```

### runtime

<p>

  **Type:**
  ```
  { mode: 'off' }
  | { mode: 'local'; type: 'pages'; persistTo?: string; bindings?: Record<string, CF_BINDING> }
  | { mode: 'local'; type: 'workers'; persistTo?: string; };
  ```
  ([CF\_BINDING type reference](https://github.com/cloudflare/workers-sdk/blob/eaa16db25103d26ef31499634a31b86caccdf7aa/packages/wrangler/src/api/startDevWorker/types.ts#L190-L219))<br />
  **Default:** `{ mode: 'off', persistTo: '' }`
</p>

Détermine si et comment le Cloudflare Runtime est ajouté à `astro dev`.
En savoir plus sur [le moteur d'exécution Cloudflare](#cloudflare-runtime).

La propriété `type` définit où votre projet Astro est déployé :

* `pages` : Déployé sur [Cloudflare Pages](https://pages.cloudflare.com/)
* `workers` : Déployé sur [Cloudflare Workers](https://workers.cloudflare.com/)

La propriété `mode` définit ce que vous voulez que le runtime supporte dans `astro dev` :

* `off` : pas d'accès au runtime en utilisant `astro dev`. Vous pouvez choisir [Preview with Wrangler](#aperçu-avec-wrangler) quand vous avez besoin d'accéder au runtime, pour simuler l'environnement de production localement.
* `local` : utilise un runtime local alimenté par miniflare et workerd, qui supporte les Bindings de Cloudflare. Seulement si vous voulez utiliser des fonctionnalités non supportées, comme `eval`, les bindings sans support local choisissent [Preview with Wrangler](#aperçu-avec-wrangler)

En `mode : local`, vous avez accès à la propriété `persistTo` qui définit où l'état des bindings locaux est sauvegardé. Cela permet d'éviter d'avoir de nouvelles bindings à chaque redémarrage du serveur de développement. Cette valeur est un répertoire relatif à votre chemin d'exécution `astro dev`. Par défaut, il est positionné à `.wrangler/state/v3` pour permettre l'utilisation des commandes clientes `wrangler` (par exemple pour les migrations). Ajoutez ce chemin à votre `.gitignore`.

## Cloudflare runtime

Le runtime de Cloudflare vous donne accès aux variables d'environnement et aux bindings de Cloudflare. Vous pouvez trouver plus d'informations dans les documents de Cloudflare [Workers](https://developers.cloudflare.com/workers/configuration/bindings/) et [Pages](https://developers.cloudflare.com/pages/platform/functions/bindings/). Selon votre type de déploiement (`pages` ou `workers`), vous devez configurer les bindings différemment.

Liaisons actuellement prises en charge :

* Variables d'environnement
* [Cloudflare D1](https://developers.cloudflare.com/d1/)
* [Cloudflare R2](https://developers.cloudflare.com/r2/)
* [Cloudflare Workers KV](https://developers.cloudflare.com/kv/)
* [Cloudflare Durable Objects](https://developers.cloudflare.com/durable-objects/)
* [Cloudflare Service bindings](https://developers.cloudflare.com/workers/configuration/bindings/about-service-bindings/)

### Config

#### Cloudflare Pages

Cloudflare Pages ne prend pas en charge un fichier de configuration.

Pour déployer votre projet de pages en production, vous devez configurer les bindings en utilisant le Dashboard de Cloudflare. Pour pouvoir accéder aux bindings localement, vous devez les configurer en utilisant l'option `runtime` de l'adaptateur.

```js title="astro.config.mjs" ins={7-10, 12-15, 17-19, 21-23, 25-27, 29-32, 34-39}
import { defineConfig } from 'astro/config';
import cloudflare from '@astrojs/cloudflare';

export default defineConfig({
  output: 'server',
  adapter: cloudflare({
    runtime: {
      mode: 'local',
      type: 'pages',
      bindings: {
        // exemple de liaison var (variable d'environnement)
        "URL": {
          type: "var",
          value: "https://example.com",
        },
        // exemple de liaison KV
        "KV": {
          type: "kv",
        },
        // exemple de liaison D1
        "D1": {
          type: "d1",
        },
        // exemple de liaison R2
        "R2": {
          type: "r2",
        },
        // exemple de liaison avec Durable Object binding
        "DO": {
          type: "durable-object",
          className: "DO",
        },
        // exemple de liaison de service
        "AUTH": {
          type: "service",
          address: "127.0.0.1:8787",
        }
      },
    },
  }),
});
```

Si vous avez besoin de définir des `secrets` en plus des variables d'environnement, vous devez ajouter un fichier `.dev.vars` à la racine du projet Astro :

```ini title=".dev.vars"
DB_PASSWORD=myPassword
```

Si vous voulez utiliser `wrangler` pour des commandes clientes, par exemple les migrations D1, vous devez également ajouter un `wrangler.toml` à la racine du projet Astro avec le contenu correct. Consultez [la documentation de Cloudflare](https://developers.cloudflare.com/) pour plus de détails.

```toml title="wrangler.toml"
name = "example"
compatibility_date = "2023-06-14"

# exemple pour D1 Binding
[[d1_databases]]
binding = "D1"
database_name = "D1"
database_id = "D1"
preview_database_id = "D1"
```

#### Cloudflare Workers

Pour déployer votre projet workers en production, vous devez configurer les bindings en utilisant un fichier de configuration `wrangler.toml` dans le répertoire racine de votre projet Astro. Pour pouvoir accéder aux bindings localement, l'adaptateur `@astrojs/cloudflare` lira également le fichier `wrangler.toml`.

```toml title="wrangler.toml"
name = "example"

# Exemple d'une liaison KV
kv_namespaces = [
    { binding = "KV", id = "KV", preview_id = "KV" },
]

# Exemple de liaison var (variables d'environnement)
[vars]
URL = "example.com"

# Exemple d'une liaison D1
[[d1_databases]]
binding = "D1"
database_name = "D1"
database_id = "D1"
preview_database_id = "D1"

# Exemple d'une liaison R2
[[r2_buckets]]
binding = 'R2'
bucket_name = 'R2'

#Exemple de liaison avec Durable Object Binding
[[durable_objects.bindings]]
name = "DO"
class_name = "DO"

# Exemple de liaison de service
[[services]]
binding = "AUTH"
service = "auth-worker"
```

Si vous avez besoin de définir des `secrets` en plus des variables d'environnement, vous devez ajouter un fichier `.dev.vars` à la racine du projet Astro :

```ini title=".dev.vars"
DB_PASSWORD=myPassword
```

### Utilisation

Vous pouvez accéder au runtime à partir des composants Astro via `Astro.locals` à l'intérieur de n'importe quel fichier `.astro`.

```astro title="src/pages/index.astro"
---
const runtime = Astro.locals.runtime;
---

<pre>{JSON.stringify(runtime.env)}</pre>
```

Vous pouvez accéder à l'exécution à partir des points d'extrémité de l'API par l'intermédiaire de `context.locals` :

```js title="src/pages/api/someFile.js"
export function GET(context) {
  const runtime = context.locals.runtime;

  return new Response('Some body');
}
```

### Typing

Si vous avez configuré `mode : advanced`, vous pouvez taper l'objet `runtime` en utilisant `AdvancedRuntime` :

```ts title="src/env.d.ts"
/// <reference types="astro/client" />

type KVNamespace = import('@cloudflare/workers-types/experimental').KVNamespace;
type ENV = {
  SERVER_URL: string;
  KV_BINDING: KVNamespace;
};

type Runtime = import('@astrojs/cloudflare').AdvancedRuntime<ENV>;

declare namespace App {
  interface Locals extends Runtime {
    user: {
      name: string;
      surname: string;
    };
  }
}
```

Si vous avez configuré `mode : directory`, vous pouvez taper l'objet `runtime` en utilisant `DirectoryRuntime` :

```ts title="src/env.d.ts"
/// <reference types="astro/client" />

type KVNamespace = import('@cloudflare/workers-types/experimental').KVNamespace;
type ENV = {
  SERVER_URL: string;
  KV_BINDING: KVNamespace;
};

type Runtime = import('@astrojs/cloudflare').DirectoryRuntime<ENV>;

declare namespace App {
  interface Locals extends Runtime {
    user: {
      name: string;
      surname: string;
    };
  }
}
```

## Plate-forme

### Headers

Vous pouvez attacher des [en-têtes personnalisés](https://developers.cloudflare.com/pages/platform/headers/) à vos réponses en ajoutant un fichier `_headers` dans le dossier `public/` de votre projet Astro. Ce fichier sera copié dans le répertoire de sortie de la compilation.

### Assets
Les assets construits par Astro sont tous nommés avec un hash et peuvent donc se voir attribuer de longs en-têtes de cache. Par défaut, Astro sur Cloudflare ajoutera un en-tête de ce type pour ces fichiers.

### Redirects

Vous pouvez déclarer des [redirections personnalisées](https://developers.cloudflare.com/pages/platform/redirects/) en utilisant les pages Cloudflare. Cela vous permet de rediriger les requêtes vers une URL différente. Vous pouvez ajouter un fichier `_redirects` dans le dossier `public/` de votre projet Astro. Ce fichier sera copié dans le répertoire de sortie de votre build.

### Routes

Vous pouvez définir quelles routes invoquent des fonctions et lesquelles sont des actifs statiques, en utilisant [Cloudflare routing](https://developers.cloudflare.com/pages/platform/functions/routing/#functions-invocation-routes) via un fichier `_routes.json`. Ce fichier est généré automatiquement par Astro.

#### `_routes.json` personnalisé

Par défaut, `@astrojs/cloudflare` va générer un fichier `_routes.json` avec des règles `include` et `exclude` basées sur les routes dynamiques et statiques de vos applications.
Cela permettra à Cloudflare de servir des fichiers et de traiter des redirections statiques sans invocation de fonction. La création d'un `_routes.json` personnalisé annulera cette optimisation automatique. Voir [la documentation de Cloudflare sur la création d'un `routes.json` personnalisé](https://developers.cloudflare.com/pages/platform/functions/routing/#create-a-_routesjson-file) pour plus de détails.

## Utilisation des modules Wasm

Voici un exemple d'importation d'un module Wasm qui répond aux requêtes en additionnant les paramètres numériques de la requête.

```js title="pages/add/[a]/[b].js"
import mod from '../util/add.wasm?module';

// instanciation à l'avance pour partager le module
const addModule: any = new WebAssembly.Instance(mod);

export async function GET(context) {
  const a = Number.parseInt(context.params.a);
  const b = Number.parseInt(context.params.b);
  return new Response(`${addModule.exports.add(a, b)}`);
}
```

Bien que cet exemple soit trivial, Wasm peut être utilisé pour accélérer des opérations de calcul intensif qui n'impliquent pas d'E/S importantes, comme l'intégration d'une bibliothèque de traitement d'images.

## Compatibilité Node.js

Cloudflare ne prend pas en charge l'intégralité de l'API d'exécution Node.js. Avec un peu de configuration, Cloudflare prend en charge un sous-ensemble des API d'exécution Node.js. Les API suivantes sont prises en charge :

* assert
* AsyncLocalStorage
* Buffer
* Crypto
* Diagnostics Channel
* EventEmitter
* path
* process
* Streams
* StringDecoder
* util

Pour utiliser ces API, votre page ou votre point d'accès doit être rendu côté serveur (et non pré-rendu) et doit utiliser la syntaxe d'importation `import {} from 'node:*'`.

```js title="pages/api/endpoint.js"
export const prerender = false;
import { Buffer } from 'node:buffer';
```

En outre, vous devez activer le drapeau de compatibilité dans Cloudflare. La configuration de ce drapeau peut varier en fonction de l'endroit où vous déployez votre site Astro. Pour des conseils détaillés, veuillez consulter la [documentation Cloudflare sur l'activation de la compatibilité Node.js](https://developers.cloudflare.com/workers/runtime-apis/nodejs).


:::note[Implications de la compatibilité des paquets]
Si un projet importe un paquet sur le serveur qui utilise les API d'exécution Node.js, cela peut causer des problèmes lors du déploiement sur Cloudflare. Ce problème survient avec les paquets qui n'utilisent pas la syntaxe d'importation `node:*`. Il est recommandé de contacter les auteurs du paquet afin de déterminer si le paquet supporte la syntaxe d'importation ci-dessus. Si ce n'est pas le cas, vous devrez peut-être utiliser un autre paquet ou changer d'adaptateur.
:::


## Support des modules Cloudflare

Tous les paquets Cloudflare (par exemple `cloudflare:sockets`) sont autorisés à être utilisés. Notez que le paquet `cloudflare:sockets` ne fonctionne pas localement sans utiliser le mode dev de Wrangler.

## Aperçu avec Wrangler

Pour utiliser [`wrangler`](https://developers.cloudflare.com/workers/wrangler/) afin d'exécuter votre application localement, mettez à jour le script de prévisualisation :

```json title="package.json"
"preview": "wrangler pages dev ./dist"
```

[`wrangler`](https://developers.cloudflare.com/workers/wrangler/) vous donne accès à [Cloudflare bindings](https://developers.cloudflare.com/pages/platform/functions/bindings), [environment variables](https://developers.cloudflare.com/pages/platform/functions/bindings/#environment-variables), et à [l'objet cf](https://developers.cloudflare.com/workers/runtime-apis/request/#incomingrequestcfproperties). Faire fonctionner le rechargement à chaud (Hot Reloading) ou le serveur de développement Astro avec Wrangler peut nécessiter une configuration personnalisée. Voir [exemples de la communauté](https://github.com/withastro/roadmap/discussions/590).

### Messages d'erreur significatifs

Actuellement, les erreurs lors de l'exécution de votre application dans Wrangler ne sont pas très utiles, en raison de la minification de votre code. Pour un meilleur débogage, vous pouvez ajouter le paramètre `vite.build.minify = false` à votre `astro.config.mjs`.

```js title="astro.config.mjs" ins={4-8}
export default defineConfig({
  adapter: cloudflare(),
  output: 'server',
  vite: {
    build: {
      minify: false,
    },
  },
});
```

[astro-integration]: /fr/guides/integrations-guide/
